Skip to content

Add system project infrastructure and project-scoped routing foundation#1209

Merged
os-zhuang merged 6 commits intomainfrom
claude/design-new-system-architecture
Apr 22, 2026
Merged

Add system project infrastructure and project-scoped routing foundation#1209
os-zhuang merged 6 commits intomainfrom
claude/design-new-system-architecture

Conversation

@Claude
Copy link
Copy Markdown
Contributor

@Claude Claude AI commented Apr 22, 2026

Implements foundational schema and provisioning for ObjectStack's new architecture with a built-in "system" project and project-scoped API routing, following Airtable's workspace/base scoping model.

Schema Changes

System Project Support

  • Added isSystem boolean field to ProjectSchema and sys_project object
  • Regular projects default to isSystem: false, system project set to true
  • Enables separation of platform infrastructure from user data

Project-Scoped Routing Configuration

  • Added enableProjectScoping and projectResolution fields to RestApiConfigSchema
  • Supports three resolution strategies: 'required', 'optional', 'auto' (default)
  • Prepares infrastructure for Airtable-style routing: /api/v1/projects/:projectId/data/...

Provisioning Service

Implemented ProjectProvisioningService.provisionSystemProject():

const service = new ProjectProvisioningService({ controlPlaneDriver });
const result = await service.provisionSystemProject();

// Returns system project with well-known UUID
console.log(result.project.id);        // '00000000-0000-0000-0000-000000000001'
console.log(result.project.isSystem);  // true
console.log(result.project.slug);      // 'system'

Characteristics:

  • Well-known UUID: 00000000-0000-0000-0000-000000000001
  • Operates on control plane DB (no separate physical database)
  • Idempotent provisioning - safe to call multiple times
  • Enterprise plan, production type, protected status

Test Coverage

Added comprehensive test suite (7 tests, all passing):

  • Regular project provisioning with isSystem=false
  • System project creation with well-known UUID
  • Idempotent system project behavior
  • Control plane persistence validation
  • Default project constraints

Documentation

Created docs/design/SYSTEM_ARCHITECTURE_IMPLEMENTATION.md:

  • Complete architecture overview and benefits
  • Migration path for existing deployments
  • Usage examples and code snippets
  • Phase 2 requirements for runtime implementation

Architecture Benefits

System Project Isolation

  • Clear separation: platform infrastructure vs user data
  • Protected from accidental deletion via isSystem flag
  • Enables centralized system package management

Project-Scoped APIs (Schema Ready)

  • Multi-tenancy foundation in place
  • Industry-standard routing pattern (Airtable, Salesforce alignment)
  • Backward compatible through 'auto' resolution strategy
  • Future-proofs for per-project quotas, permissions, billing

Phase 2 (Future Work)

Runtime implementation deferred to next PR:

  • REST server route registration with project context
  • HTTP dispatcher projectId extraction logic
  • Client SDK project-scoped API methods
  • Integration and E2E testing

Current implementation (~50% of total changes) provides production-ready schema and provisioning that can be safely deployed without breaking existing functionality.

Claude AI and others added 4 commits April 21, 2026 17:38
- Added isSystem field to ProjectSchema in cloud/project.zod.ts
- Added is_system field to sys_project object schema
- Implemented provisionSystemProject() method for bootstrapping platform
- System project uses well-known ID and operates on control plane DB
- Idempotent provisioning - returns existing if already created

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
- Added enableProjectScoping flag to RestApiConfigSchema
- Added projectResolution strategy (required/optional/auto)
- Enables /api/v1/projects/:projectId/data/... routing pattern
- Control plane routes remain unscoped
- Backward compatible with 'auto' strategy

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
- Add unit tests for provisionProject() with isSystem field
- Add unit tests for provisionSystemProject() method
- Test idempotent behavior of system project creation
- Test system project metadata and well-known UUIDs
- Fix missing isSystem field in provisionProject()
- All 7 tests passing

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
- Document all completed Phase 1 implementation work
- Detail system project schema and provisioning
- Explain project-scoped routing configuration
- Provide migration path and usage examples
- Define Phase 2 runtime implementation requirements
- Include benchmarking against industry standards (Airtable, Salesforce)

Co-authored-by: xuyushun441-sys <255036401+xuyushun441-sys@users.noreply.github.com>
@vercel
Copy link
Copy Markdown

vercel Bot commented Apr 22, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
objectstack-demo Ready Ready Preview, Comment Apr 22, 2026 4:11am
spec Ready Ready Preview, Comment Apr 22, 2026 4:11am

Request Review

@github-actions github-actions Bot added documentation Improvements or additions to documentation tests size/l labels Apr 22, 2026
Comment on lines +4 to +9
import {
ProjectProvisioningService,
MockProjectDatabaseAdapter,
NoopSecretEncryptor,
type ProjectDatabaseAdapter,
} from './project-provisioning.js';
- Added tests for project-scoped routing in RestServer, covering unscoped, auto, and required modes.
- Enhanced DispatcherPlugin to support project-scoping configuration.
- Updated HttpDispatcher to resolve projectId from URL paths.
- Introduced SystemProjectPlugin to ensure the existence of a system project.
- Created integration tests for project-scoped REST routing in the client.
- Added tests for SystemProjectPlugin to verify provisioning behavior.
if (filterValue) {
if (this.parent._isFilterAST(filterValue) || Array.isArray(filterValue)) {
queryParams.set('filter', JSON.stringify(filterValue));
} else if (typeof filterValue === 'object' && filterValue !== null) {
@os-zhuang os-zhuang marked this pull request as ready for review April 22, 2026 04:06
@os-zhuang os-zhuang merged commit 51eb6fc into main Apr 22, 2026
10 of 12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/xl tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants